All DatabasesInside Mac - Basic Toolbox
Presenting the Default Interface
Presenting the Default Interface For dialogs with no special requirements
If your application has no special interface requirements, you can use the
StandardGetFile and StandardPutFile procedures to display the default dialog
boxes for opening and saving documents.
The system 7.0 Standard File Package introduces a number of user interface
enhancements, most of which have no effect on your application. Most noticeably, the
system 7.0 standard file dialog boxes use a slightly different point of view. Instead of
displaying only one volume at a time and showing the root of that volume at the top of
the hierarchy, the file list now displays all mounted volumes and shows the desktop as
the top level of the hierarchy. The Drive button, which previously allowed users to
move among all mounted volumes, is now the Desktop button, which returns the
display to the top of the hierarchy.
You use the StandardGetFile procedure when you want to let the user choose a file
to be opened. The first Figure below illustrates a sample dialog box displayed by
StandardGetFile.
The default Open dialog box
When you call StandardGetFile, you can supply a list of the file types that your
application can open. StandardGetFile then displays only files of the specified types.
You can also supply your own filter function to determine which files are displayed.
(See Opening Files for details.)
When the user is opening a document, StandardGetFile interprets keystrokes as
selectors in the displayed list. Pressing A, for example, selects the first item in the
list that starts with the letter a (or, if no items in the list start with the letter a, the
item that starts with the letter closest to a). The Standard File Package sets a
timer on keystrokes: keystrokes in rapid succession form a string; keystrokes spaced
in time are processed separately.
When the user is saving a document, StandardPutFile can direct keystrokes to
either of two targets: the filename field or the displayed list. When the dialog box first
appears, keystrokes are directed to the filename field. If the user presses the Tab key
or clicks to select an item in the displayed list, subsequent keystrokes are interpreted
as selectors in the displayed list. Each time the user presses the Tab key, keyboard
input shifts between the two targets. (The list at the end of this section describes all
keystrokes that affect the standard file dialog boxes.)
When the user is saving a file, the new Save dialog box offers the option of creating a
new folder, as illustrated below.
The default Save dialog box
When the user clicks New Folder , the Standard File Package presents a
subsidiary dialog box like the example below.
The New Folder dialog box
If the user asks to save a file with a name that already exists at the specified location,
the Standard File Package displays a subsidiary dialog box to verify that the new
file should replace the existing file.
The name conflict dialog box
The StandardGetFile and StandardPutFile procedures always display the new
dialog boxes. The procedures available before system 7.0 (SFGetFile , SFPutFile ,
SFPGetFile , and SFPPutFile ) also display the new dialog boxes when running in
system 7.0, unless the application has customized the dialog box. For more details on
how the system 7.0 Standard File Package handles earlier procedures, see
Compatibility With Earlier Procedures under
Customizing Your Interface.
StandardGetFile and StandardPutFile fill in the reply record and return when
the user completes the dialog box-either by selecting a file and clicking Save or
Open, or by clicking Cancel. Your application checks the values in the reply record
to see what action to take, if any. If the selected item is an alias for another item, the
reply record describes the target of the alias. (See the Finder Interface for a
description of aliases.)
You can pass file descriptions directly from the Standard File Package to the
File Manager. The new reply record identifies files with file system specification
records, which are recognized by a new set of high-level File Manager functions.
(See the File Manager for a description of the new File Manager functions that use
file system specification records.)
The following code example illustrates how an application calls first the
Standard File Package and then the File Manager after the user chooses Open
from the File menu.
// Opening a document
// Assuming inclusion of
void LetMeCheck (OSErr fsOpenErr);
StandardFileReply mySFR; ˜// reply record
SFTypeList myTypeList; // list of types to display
OSErr fsOpenErr; // error returned by open function
short fsRefNum; // by open function
myTypeList[0] = 'MDOC'; // set up type list
myTypeList[1] = 'YDOC';
StandardGetFile(nil, 2, myTypeList, &mySFR);// display dialog box
if (mySFR.sfGood) ˜// user clicks Open
{
fsOpenErr = FSpOpenDF(&mySFR.sfFile, fsCurPerm, &fsRefNum);
// open the file
LetMeCheck(fsOpenErr); ˜// routine to check errors
// open document through reference number returned by FSpOpenDF
}
The Standard File Package now recognizes a longer list of keyboard equivalents
during dialogs.
Keystrokes Action
Up Arrow Scroll up (backward) through displayed
list
Down Arrow Scroll down (forward) through
displayed list
Command-Up Arrow Display contents of parent
Command-Down Arrow Display contents of selected directory or
volume
Command-Left Arrow Display contents of previous volume
Command-Right Arrow Display contents of next volume
Command-Shift-Up Arrow Display contents of desktop
Command-Shift-1 Eject disk in drive 1
Command-Shift-2 Eject disk in drive 2
Tab Move to next keyboard target
Return or Enter Invoke the default option for the dialog
box (Open or Save)
Escape or Command-. Cancel
Command-O Open the selected item
Command-D Display contents of desktop
Command-N Create a new folder
Option-Command-O or
Option-[click Open] Select the target of the selected alias
item instead of opening it
When the user selects a button in the dialog box using a keyboard equivalent, the
button flashes.
Referenced by (2):